home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / libelf / elf_rawfile.z / elf_rawfile
Encoding:
Text File  |  2002-10-03  |  4.5 KB  |  82 lines
  1. ELF_RAWFILE(3E)                                      Last changed: 10-13-98
  2.  
  3.  
  4. NNAAMMEE
  5.      eellff__rraawwffiillee - Retrieves uninterpreted file contents
  6.  
  7. SSYYNNOOPPSSIISS
  8.      cccc [_f_l_a_g ...] _f_i_l_e ...  --lleellff [_l_i_b_r_a_r_y ...]
  9.  
  10.      ##iinncclluuddee <<lliibbeellff..hh>>
  11.  
  12.      cchhaarr **eellff__rraawwffiillee((EEllff **eellff,, ssiizzee__tt **ppttrr));;
  13.  
  14.      ##ddeeffiinnee __LLIIBBEELLFF__XXTTNNDD__6644
  15.  
  16.      cchhaarr **eellff__rraawwffiillee((EEllff **eellff,, EEllff6644__XXwwoorrdd **ppttrr));;
  17.  
  18. IIMMPPLLEEMMEENNTTAATTIIOONN
  19.      IRIX systems
  20.  
  21. DDEESSCCRRIIPPTTIIOONN
  22.      eellff__rraawwffiillee returns a pointer to an uninterpreted byte image of the
  23.      file.  This function should be used only to retrieve a file being
  24.      read.  For example, a program might use eellff__rraawwffiillee to retrieve the
  25.      bytes for an archive member.
  26.  
  27.      A program may not close or disable [see eellff__ccnnttll(3E)] the file
  28.      descriptor associated with eellff before the initial call to eellff__rraawwffiillee,
  29.      because eellff__rraawwffiillee might have to read the data from the file if it
  30.      does not already have the original bytes in memory.  Generally, this
  31.      function is more efficient for unknown file types than for object
  32.      files.  The library implicitly translates object files in memory,
  33.      while it leaves unknown files unmodified.  Thus, asking for the
  34.      uninterpreted image of an object file may create a duplicate copy in
  35.      memory.
  36.  
  37.      eellff__rraawwddaattaa [see eellff__ggeettddaattaa(3E)] is a related function, providing
  38.      access to sections within a file.
  39.  
  40.      If ppttrr is non-null, the library also stores the file's size, in bytes,
  41.      in the location to which ppttrr points.  If no data are present, eellff is
  42.      null, or an error occurs, the return value is a null pointer, with
  43.      zero optionally stored through ppttrr.
  44.  
  45. NNOOTTEESS
  46.      A program that uses eellff__rraawwffiillee and that also interprets the same file
  47.      as an object file, potentially has two copies of the bytes in memory.
  48.      If such a program requests the raw image first, before it asks for
  49.      translated information (through such functions as eellff__ggeetteehhddrr,
  50.      eellff__ggeettddaattaa, and so on), the library ``freezes'' its original memory
  51.      copy for the raw image.  It then uses this frozen copy as the source
  52.      for creating translated objects, without reading the file again.
  53.      Consequently, the application should view the raw file image returned
  54.      by eellff__rraawwffiillee as a read-only buffer, unless it wants to alter its own
  55.      view of data subsequently translated.  In any case, the application
  56.      may alter the translated objects without changing bytes visible in the
  57.      raw image.
  58.  
  59.      Multiple calls to eellff__rraawwffiillee with the same ELF descriptor return the
  60.      same value; the library does not create duplicate copies of the file.
  61.  
  62.      The use of a ssiizzee__tt in a 32-bit compile with eellff__rraawwffiillee is
  63.      unfortunate, since that makes it impossible to deal with certain
  64.      object files.  If, when the 32-bit application is compiled,
  65.      __LLIIBBEELLFF__XXTTNNDD__6644 is defined, then the function interface changes to
  66.      have 64-bit fields.  If __LLIIBBEELLFF__XXTTNNDD__6644 is defined at compile-time,
  67.      then instead of linking with --lleellff, link with --lleellff__xxttnndd.  There is a
  68.      corresponding --llddwwaarrff__xxttnndd.  It is essential that a 32-bit application
  69.      compiled with __LLIIBBEELLFF__XXTTNNDD__6644 be entirely compiled with
  70.      __LLIIBBEELLFF__XXTTNNDD__6644 defined.
  71.  
  72.      Applications that are built as 64-bit applications can ignore
  73.      __LLIIBBEELLFF__XXTTNNDD__6644; it has no effect on them and 64-bit applications
  74.      always link with --lleellff, never with --lleellff__xxttnndd.
  75.  
  76. SSEEEE AALLSSOO
  77.      eellff(3E), eellff__bbeeggiinn(3E), eellff__ccnnttll(3E), eellff__ggeettddaattaa(3E),
  78.      eellff__ggeetteehhddrr(3E), eellff__ggeettiiddeenntt(3E), eellff__kkiinndd(3E)
  79.  
  80.      This man page is available only online.
  81.  
  82.